package com.ceair.service;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.ceair.entity.SysRole;
import com.ceair.entity.request.role.DeleteRoleReq;
import com.ceair.entity.request.role.QueryRoleReq;
import com.ceair.entity.request.role.RoleInOrUpReq;
import com.ceair.entity.request.role.UpdateRoleAuthorityReq;
import com.ceair.entity.vo.role.RoleAuthorityVO;
import com.ceair.entity.vo.role.SysRoleVO;

import java.util.List;

/**
 * <p>
 * 系统角色表 服务类
 * </p>
 *
 * @author wangbaohai
 * @since 2025-02-25
 */
public interface ISysRoleService extends IService<SysRole> {

    /**
     * 使用分页查询角色信息
     *
     * @param queryRoleReq 包含分页和查询条件的请求对象
     * @return 返回查询到的角色信息分页对象
     */
    Page<SysRole> queryRoleWithPage(QueryRoleReq queryRoleReq);

    /**
     * 保存角色信息
     * <p>
     * 该方法用于接收一个角色请求对象，并将其保存到系统中
     * 它可以处理角色的创建或更新请求，具体逻辑取决于传入参数的属性
     *
     * @param roleInOrUpReq 角色请求对象，包含需要保存或更新的角色信息
     * @return SysRoleVO 返回一个包含操作结果的角色视图对象
     */
    SysRoleVO save(RoleInOrUpReq roleInOrUpReq);

    /**
     * 查询角色权限
     * <p>
     * 根据角色ID查询并返回该角色的权限信息此方法主要用于角色权限管理，
     * 以便用户了解特定角色拥有哪些系统权限
     *
     * @param roleId 角色ID，用于标识需要查询的角色
     * @return RoleAuthorityVO 返回一个包含角色权限信息的对象如果角色ID不存在，
     * 则返回null或空对象具体行为应根据系统错误处理策略确定
     */
    List<RoleAuthorityVO> queryRoleAuthority(Long roleId);

    /**
     * 更新角色权限
     *
     * @param updateRoleAuthorityReq 包含角色权限更新的请求对象
     * @return String 返回一个包含操作结果的字符串，用于表示更新操作的结果
     */
    Boolean updateRoleAuthority(UpdateRoleAuthorityReq updateRoleAuthorityReq);

    /**
     * 删除角色信息
     * <p>
     * 该方法用于根据提供的角色信息删除系统中的角色通常，DeleteRoleReq对象中会包含角色的唯一标识符，
     * 如角色ID，以确定要删除的角色对象此外，该方法可能还会检查角色是否可以被删除，例如，检查是否有其他
     * 对象引用了该角色，以确保数据的一致性和完整性
     *
     * @param deleteRoleReq 包含要删除角色的相关信息的对象
     * @return 如果角色删除成功，则返回true；如果删除失败（例如，角色不存在或无法删除），则返回false
     */
    Boolean delete(DeleteRoleReq deleteRoleReq);

    /**
     * 根据用户ID查询角色ID列表
     *
     * @param userId 用户ID，用于查询角色信息
     * @return 返回一个包含用户所拥有的角色ID的列表如果用户没有关联任何角色，则返回空列表
     */
    List<Long> queryRoleIdsByUserId(Long userId);
}
